                   THE HOME OF VB/ISAM AND CB/ISAM

                                                                   06/09/96
                Enhancements for version 2.4 16 bit VB/ISAM
                                  for VB3
                                (VBIS24.DLL)

This new release V 2.4 contains both "Relative Move", "Raw Record" functions
and enhanced format strings. Additionally, we have made some enhancements to
the shared modes of operation, and have added new raw Functions which are
somewhat faster than the structured Get and Put Functions.

For this release, a new version of DREMAKE has been included which requires
the map and finder rebuild to be remade using MAKEFF.  This new program
(MAKEFF) will repair and recreate a map file and finder for any VB/ISAM
file of any Group size and for any number of groups. Please read the
new Documentation for REMAKE for additional features.

    NOTE for Compuserve Distribution only: DREMAKE and MAKEFF are not
    included in the ZIP file.  To download DREMAKE
    GO VBPJFO, select file keyword VBISAM.


The following Functions are included in the new .BAS file.

*****************************************************************************
                        NEW OPEN FUNCTION

VmxOpen         (DatasetName$, CacheSize%, AccessMode%, DatasetNumber&,
                 LicenseKey$)

                The parameters are the same as described in previous versions
                of the manual with the following exceptions:

DatasetNunmber% is an integer value.

LicenseKey$     is a string created especially for you by Software Source.
                This license key is selected to allow you access to those
                features for which you are licensed and registered to use.

                The following behavior is valid:

        LicenseKey$ = ""            : A message box will
                                      apear telling how to license
                                      VB/ISAM

                   if AccessMode% = 0, Return Code = VIS_OK
                                    1, Return Code = VIS_OK
                                    2, Return Code = VIS_BAD_PARAMETER_VALUE
                                    3, Return Code = VIS_BAD_PARAMETER_VALUE

        LicenseKey$ = (Bad key)     : No message box appears

                   if AccessMode% = 0, Return Code = VIS_INVALID_PASSWORD
                                    1, Return Code = VIS_INVALID_PASSWORD
                                    2, Return Code = VIS_INVALID_PASSWORD
                                    3, Return Code = VIS_INVALID_PASSWORD

        LicenseKey$ = (valid MX Password)

                   if AccessMode% = 0, Return Code = VIS_OK
                                    1, Return Code = VIS_OK
                                    2, Return Code = VIS_BAD_PARAMETER_VALUE
                                    3, Return Code = VIS_BAD_PARAMETER_VALUE

        LicenseKey$ = (valid MU Password)

                   if AccessMode% = 0, Return Code = VIS_OK
                                    1, Return Code = VIS_OK
                                    2, Return Code = VIS_OK
                                    3, Return Code = VIS_OK


*****************************************************************************

                        RELATIVE MOVE POINTER

VmxMovePtr  (DatasetNumber%, SecIndexField%, RelativeCount&, RelOption%)

DatasetNumber%  is the same as returned from VmxOpen.

SecIndexField%  is the secondary index on which to perform the move ptr.

RelativeCount&  is a plus(+) or minus(-) (long) value of the records to skip.

RelOption%      is 1 if you want to DISABLE the internal equivalent DoEvents
                calls, otherwise it should be 0.

Note: Only one VmxMovePtr can be in operation at a time and will not respond
      again (except with VIS_BUSY), until it has completed or been terminated
      by VmxCancel.  Since, in larger data sets,  this operation has the
      potential of taking a very long time, VmxMovePtr has been made an
      asynchronous operation. This allows other parts of your application
      (and the rest of Windows) to run just fine. In other words, the system
      won't go out to lunch until this operation finishes - It really does
      multi-task. Although, if any other attempt is made to access a VB/ISAM
      function which will interfere with the relative move, that function will
      return VIS_BUSY until the VmxMovePtr operation is complete or terminated.
      This includes any other calls to VmxMovePtr.

The possible return codes are:

          VIS_OK
          VIS_BAD_PARAMETER_VALUE
          VIS_BAD_HANDLE
          VIS_OUT_OF_MEMORY
          VIS_BUSY
          VIS_DISK_ERROR
          VIS_DATA_VALIDITY_CHECK
          VIS_NOT_FOUND   (end of list before count exhausted)
          VIS_INTERRUPTED (will return only if VmxCancel was called)
*****************************************************************************
VmxCancel  (DatasetNumber%)

This Function will cancel any currently active VmxMovePtr operation on
the dataset specified.

*****************************************************************************

                        RAW MODE FUNCTIONS

VmxStoreField  (DatasetNumber%, RecFormat$, Record$, FieldNo%, FieldType$,
                FldData As Any)

This Function will Store data from FldData into the "RAW" record pointed to
by Record$ (from a previous VmxGet/XNATIVE).

DatasetNumber%  is the same as returned from VmxOpen. This parameter is
                optional but must not be specified if the RecFormat$
                parameter is used, as described below.

RecFormat$      is the record format of the source data string.  This MUST
                correspond to the data as defined in the original create of
                the data set. This parameter is optional but must not be
                specified if the DatasetNumber% field is used, as described
                above.

        NOTE:    either one or the other of the above parameters must be
                 specified but not both.

Record$         is the "string" of data returned by VmxGet using the XNATIVE
                mode of the read.

FieldNo%        is the field into which the FldData data will be placed.

FieldType$      is a string value which defines the field type. I.E. "$"
                defines a string "%" defines an integer.

FldData         is the variable containing the data to be stored into Record$.
                Its inherent type must be what is defined in the FieldType$
                parameter. Furthermore, it must correspond to the field
                specified in Record$ that is defined above. It may not be
                a Varient type.
*****************************************************************************

VmxFetchField  (DatasetNumber%, RecFormat$, Record$, FieldNo%, FieldType$,
               RFldData As Any)

This Function will fetch a field from the string data (Record$) read by
VmxGet using the XNATIVE option. The data will be stored into the variable
RFldData as the type specified by FieldType$. The definitions and
descriptions for the parameters are the same as for the VmxStoreField
function.  The way the raw functions, VmxStoreField and VmxFetchField
are used is diagrammed by the following:

        VmxGet(Dsn%, 0, XNEXT + XNATIVE, sk$, Rsk$, Rpk$, Record$)
        '       Notice: XNATIVE is used in place of XGET_DATA
        VmxFetchField(Dsn%, "$$$$%$$", Record$, 4, "$", Fd4$)
        VmxFetchField(Dsn%, "$$$$%$$", Record$, 5, "%", Fd5%)
        data% = 9
        VmxStoreField(Dsn%, "$$$$%$$", Record$, 5, "%", data%)
        VmxStoreField(Dsn%, "$$$$%$$", Record$, 2, "$", "Test String")
        NewKey$ = "ID123"
        VmxPut(Dsn%, NewKey$, Record$, ADD_OR_REPLACE + XNATIVE)

*****************************************************************************


                        NEW FORMAT STRING ENHANCEMENTS


Here are two introductory examples of simple format description strings:

"%, %, $*15, #"    Two integers, a 15-byte fixed-length string, and a Double.

"!, A100%, $, $*20, %"   A Single, a 100-element integer array, a
                         variable-length string, a 20-byte fixed-length
                         string, an integer.


Rules for constructing format description strings are as follows:

You must describe each "piece" of a Record in its format description string.
You may (optionally) separate the piece descriptions with spaces and/or
commas.  A "piece" is either an individual data item (such as an integer)
or an array of individual data items (such as an array of integers).

Represent individual data items with the standard type-declaration characters
used in Visual Basic, as follows:

        %       Integer
        &       Long
        !       Single
        #       Double
        @       Currency
        $*n     Fixed-length string, n bytes long
        $       Variable-length string

(Note that there's no representation for "variants." That's because variants
 don't really exist.)

Represent arrays with the letter "A", the number of array elements, and the
data type (as above).  For example:

        A50%            an array of 50 integers.
        A50$*10 an array of 50 fixed-length strings, each 10 bytes.

If you want to pack an array of more than one dimension, multiply the bounds
to arrive at the total number of elements.  For example, a two-dimensional
array with 6 rows and 4 columns has 24 elements.

*** NOTE:  In VB3 (and earlier versions), the Visual Basic "Option Base"
statement does not affect arrays within Types; see the VB3 Language Reference
manual, page 420.  The safest thing to do is to define the bounds of such
arrays explicitly -- for example, MyArray (1 To 10).

If you have a series of identical consecutive pieces in your format
description string, you can (optionally) save space by representing such
repeating pieces with a "repeat count":  the letter "R," the number of times
the piece description would otherwise appear, and the piece description.  For
example:

        R4%             equivalent to %, %, %, %
        R4A50%  equivalent to A50%, A50%, A50%, A50%
        R4A50$*10       equivalent to A50$*10, A50$*10, A50$*10, A50$*10

*** WARNING:  Don't confuse "repeated pieces" with "pieces." For example, the
              format description string "R5%, #, R10A3@" contains 16 pieces,
              not three.

You may not repeat groups of pieces, nor may you "nest" repeats; that is,
there is no such syntax as, for example, R5(%, #, @) or R5R3%.

NEW INFORMATION FILE - NETWORK TUNING

Every computer running applications using VB/ISAM  MU 2.33 or later, may
optionally have a file in the Windows directory named VBISAM.INI.  This file
contains adjustable parameters under the "[Options]" heading.

LockRetries     is the number of times VB/ISAM will try to lock the map
                before returning VIS_BUSY.  Map locking is required in some
                circumstances to ensure data integrity and consistency.  It
                is then the responsibility of the application software to
                either try again or take some other action.

TimeDelay       is the initial number of milliseconds to wait if the lock is
                busy.  After waiting,  the next retry is executed.  If the
                lock is still busy,  the wait time before the next retry is
                cut in half.  This continues until the wait time reaches
                MinDelay milliseconds.  All subsequent waits are at least
                MinDelay milliseconds each,  until the retry count is exhausted.
                Once a lock is achieved, the wait time returns to the initial
                TimeDelay value.  If VBISAM.INI does not exist, LockRetries
                defaults to 255, TimeDelay defaults to 5, and MinDelay
                defaults to 5.  Larger values for TimeDelay tend to reduce
                lock contention for some large networks (25 workstations +).
                For very high speed systems, the optimum value for TimeDelay
                may be above 250 with MinDelay=1.  If you experience significant lock
                contention, as evidenced by some systems never getting map
                lock access, experiment with larger values for TimeDelay.

                A general rule to follow is:

                       Use the smallest values that work appropriatly for
                       your system!

MinDelay        Sets the lower value for which the system will wait befor
                attempting another re-try. Times are in Ms.

For applications with more than 25 simultaneous users, we found the following
setting to work well:

                [Options]
                LockRetries=255
                TimeDelay=100
                MinDelay=10

Good Luck!
Tony

compuserve:  75443,134
Internet:  75443.134@compuserve.com
Software Source
835 Blossom Hill Rd
San Jose, CA 95123
      or
P.O. Box 23640
San Jose,  CA 95153-3640

Voice (408)363-0985
Fax (408)363-0987
